/**
 * @file tts_bridge.h
 * @brief C++ TTS模块的C语言兼容接口头文件
 * @details 该文件声明了一组C函数，作为C++实现的文本转语音(TTS)功能的桥梁。
 * 任何C语言项目只需包含此头文件，即可调用底层的C++ TTS功能。
 * @version 1.0
 * @date 2025-07-07
 */

#ifndef TTS_BRIDGE_H
#define TTS_BRIDGE_H

// --- C/C++ 兼容性处理 ---

// 这是一个标准的宏，用于在C和C++代码之间建立兼容性。
// `__cplusplus` 是一个由所有C++编译器预定义的宏。
#ifdef __cplusplus
// 如果当前是C++编译器在编译此文件（例如，在编译 tts_bridge.cpp 时），
// 则使用 extern "C" 来告诉编译器，花括号内的函数应遵循C语言的链接规范
// (即，不要进行名字修饰 Name Mangling)，以便C链接器能够找到它们。
extern "C" {
#endif

// --- C 语言公共接口函数声明 ---

/**
 * @brief (C接口) 初始化讯飞TTS SDK。
 * @details 在调用任何其他TTS函数之前，必须先调用此函数一次，以完成SDK的
 * 全局初始化和鉴权。
 * @return int 成功返回0, 失败返回-1。
 */
int init_tts_sdk_c();

/**
 * @brief (C接口) 将文本合成为语音文件。
 * @details 这是一个阻塞函数。它会发起TTS请求，并等待直到音频文件
 * 完全生成或发生错误/超时后才返回。
 * @param text 要合成的UTF-8编码的文本字符串。
 * @param outputPath 生成的音频文件的保存路径 (例如 "./output.mp3")。
 * 函数会覆盖已存在的同名文件。
 * @return int 成功返回0，失败返回-1。
 */
int text_to_speech_c(const char* text, const char* outputPath);

/**
 * @brief (C接口) 反初始化并释放讯飞TTS SDK资源。
 * @details 在程序结束时调用此函数，以确保所有由SDK分配的资源都
 * 被正确清理。
 */
void uninit_tts_sdk_c();


#ifdef __cplusplus
// extern "C" 块的结束括号
}
#endif

#endif // _TTS_BRIDGE_H_